Introduction

wrAnalytics is a complete Analytics platform that runs on your own server that allows you to run your own analytics site. Think of it as your own Google Analytics, getClicky, goSqaured platform, allowing you to run the system and take in payments for upgrades of packages for more sites and better historical data. Or you can run the platform and have it managing all of your clients sites in one easy place.

The system can be easily configured to allow you to turn on and off different packages, turn on and off registration and upgrades and can be fully themed easily based on the excellent Laravel blade templating engine. The plaform ships with two themes, one called Basic - which is based off bootstrap and is commented so you can see how it was put together (perfect for baseing themes off!) and one called Full - which is a fully, production ready theme with marketing pages. Its the one we use for all of our clients, so you know its mobile ready and full working.

As this is a whole platform, it is recommended to install on its own domain, or sub-domain. The platform can be integrated into your current systems by its embed code that is generated when creating a site.

Server requirements

wrAnalytics has a few system requirements. You will need to make sure your server meets the following requirements:

• PHP >= 5.5.9
• OpenSSL PHP Extension
• PDO PHP Extension
• Mbstring PHP Extension
• Tokenizer PHP Extension

We find that running the system on a Digitalocean $5 a month droplet perfect - click this link to sign up to Digitalocean now, and get $10 free!

Metrics collected

Out of the box, wrAnalytics collects 12 metrics. It can collect these metrics by generating a javacript snippet users will have to place on there websites pages. You can find the snippet on the sites settings page inside the users logged in panel. The default metrics collected are:

• Unique visitors
• Page visited
• What device type was used
• Referer
• Location - Country and City
• Operating systems and version number
• Browser and version number
• Time on site
• Page load time (on supported browsers)
• System render time

New metrics can be easily added by editing the javascript to collect the data, and the visit API to insert it into the database. You can view how to do that in the How to modify code section.

Installation on a server

Average time for installation: 10 minutes

It is relatively simple to install wrAnalytics. Please follow these steps:

1. Copy all your files from the Source directory to your folder.
2. Edit the test.env file you'll find in the project root. You can find more information on the env file here. The main variables you will need to change are the Database and Mail variables. You can find out more information on this in the Setup and configuration section. Change these to match your database and email information.
3. Rename the test.env file to .env.
4. On the command line, run composer install - this will install all the dependencies for the project.
5. On the command line, run this line: php artisan key:generate- it will generate you a safe and secure application key to make sure your system is safe from CSRF and XSS.
6. Make the storage and bootstrap/cache folders writeable. The command to do this on linux is chmod 777 -R foldername where the foldername is the folder you wish to make writeable. You can also do this using SFTP or FTP (I use FileZilla) by right clicking the folder, selecting File Permissions, changing the Numeric Value to 777 and marking the Recurse into subdirectories checkbox.
7. Go to your domain, and you should see a webpage - although it might be showing an error. This is fine, as you don't the have the database installed! Navigate to http://yourwebsite.com/install/home to be prompted to use the database installer.
8. Follow this installer, and once completed your site should be ready to go!
9. Once you have completed the database installation, go to your files again, and find the config/analytics.php file. Make sure the installed variable is changed to true. Once this is done, the database installer will show an error and not be able to run again.
10. Finally, you'll need to setup a CRON job so the system can delete old data. You can find out how to setup cron jobs here. You'll need to add * * * * * php /path/to/artisan schedule:run >> /dev/null 2>&1 where the path/to/artisan is the location of the artisan file in your project root.

Installation on shared host

Average time for installation: 20 minutes

It is relatively simple to install wrAnalytics. Please follow these steps:

1. Copy all your files from the Source directory to a folder that is NOT public_html. Can be directory above or below.
2. In cpanel open Select PHP version and choose 5.4 or 7.0
3. Edit the test.env file you'll find in the project root. You can find more information on the env file here. The main variables you will need to change are the Database and Mail variables. Change these to match your database and smtp information.
4. Rename the test.env file to .env.
5. Connect to hosting using SSH. On the command line, run composer install - this will install all the dependencies for the project.
6. Now, still using the SSH command line, run this line: php artisan key:generate- it will generate you a safe and secure application key to make sure your system is safe from CSRF and XSS.
7. Make the storage and bootstrap/cache folders writeable. The command to do this on linux is chmod 777 -R foldername where the foldername is the folder you wish to make writeable. You can also do this using SFTP or FTP (I use FileZilla) by right clicking the folder, selecting File Permissions, changing the Numeric Value to 777 and marking the Recurse into subdirectories checkbox.
8. Copy everything from SourceDirectory/public to public_html
9. Open public_html/index.php and set:

   require DIR.'/../myproject/bootstrap/autoload.php';
   									$app = require_once DIR.'/../myproject/bootstrap/start.php';

10. At the top of the index.php file, after <?php make a new line, and put ini_set('eaccelerator.enable', 0);
11. Go to your domain, and you should see a webpage - although it might be showing an error. This is fine, as you don't the have the database installed! Now navigate to http://yourwebsite.com/install/home to be prompted to use the database installer.
12. Follow this installer, and once completed your site should be ready to go!
13. Once you have completed the database installation, go to your files again, and find the config/analytics.php file. Make sure the installed variable is changed to true. Once this is done, the database installer will show an error and not be able to run again.
14. Finally, you'll need to setup a CRON job so the system can delete old data. Each shared host is different, but here is a tutorial for cPanels. You'll want to setup the cron for Midnight daily, and the command you'll want to run is php path/to/artisan schedule:run >> /dev/null 2>&1 where path/to/artisan is the location of the artisan file in your project root.

Setup and configuration

Now you have installed the platform on your server, you'll want to make it yours! Firstly, login to the user panel (http://yourwebsite.com/auth/login) and type in your admin username and password. Now click the admin panel link, and then click Settings in the top bar. On this page, as you can see instructions as to what each option does.

The settings page inside the admin panel.

You'll want to edit the mail information in the .env file at some point as well, to point to your SMTP servers. Personally, we use Postmark as our mail server, as its super easy, convient to setup and comes with 25,000 free emails. Laravel supports any SMTP server.

Setup Payments

Its really simple get payments up and ready for wrAnalytics. We recommend doing this with a Sandbox account at first, to make sure you get to grips with everything. You can get a sandbox account from https://www.braintreepayments.com/get-started.

1. You need to edit the config/analytics.php file.
2. Scroll the options for Braintree Integrations - and enter your credentials there. You can get your credentials in your braintree profile. You can find out more info on this page: https://articles.braintreepayments.com/control-panel/important-gateway-credentials.
3. Now you will need to setup a webhook to recieve updates from subscriptions - things such as payments, non-payments and cancellations. Navigate to the Webhook setting (you can find out how to do that here). Create a new webhook - the Destination URL should be http://yourwebsiteurl.com/api/webhook/braintree and you'll need to select the options called Canceled, Charged Successfully and Charged Unsuccessfully.
4. Make sure you set the right enviroment. If you set it to sandbox you'll have to use your sandbox credentials, and you'll not process any real cards. This is perfect for testing - you can find test cards to use on this site: https://developers.braintreepayments.com/reference/general/testing/php#credit-card-numbers. If you set it to production then the payment system will be live, and will take money from your users if they choose those options.

Great - you can now process payments!

Packages

Packages are the memberships that your users select that enable them to have a better experience on your platform. You can choose to have as many packages as you want on your platform, and you can also choose to charge money for them. To create or edit a platform, please navigate to your admin panel, and select the packages tab. From here, you'll be able to edit or create a package.

The options you can select to make a package are:

• Show Adverts - this lets you choose to display adverts to users who use this package. Adverts can be changed by checking out the next documentation section.
• Daily hits allowed - this option lets you set how many hits each site may be recorded a day. If you enter 0, it means there is no limit.
• How long to keep historical data in days - this option lets you set how long data is kept for. If you enter 0, it means there is no limit, and data will never be deleted.
• How many sites allowed - this option lets you set how many sites the user can have. If you enter 0, it means there is no limit.

The next options are to do with the cost of the package for your user. Please make sure you have setup your payment section before creating packages that require payments! There are three types of costs you can decide on:

• A free package - you set this by entering 0 in the Cost box.
• A one-off payment - you set this by entering the cost in the Cost box, and selecting One-off payment in the Cost time period dropdown. This payment will be taken from the customer when they select this option, and they will be set to that package forever.
• A subscription - you set this by you set this by entering the cost in the Cost box, and selecting Monthly or Yearly in the Cost time period dropdown. Before you select this, you will need to create the subscription in Braintree. You can find more information on this on this page: https://articles.braintreepayments.com/guides/recurring-billing/plans. Once you have created it, the Plan ID of the subscription needs to be entered in the Braintree ID box.

The braintree subscription page - circled is the Plan ID.

If you have created a subscription package - the payments will be taken on the dates you have entered in Braintree when creating your plan. If for any reason the user cancels, or doesn't pay for the package they will automatically be removed from the package and take on the default package.

Setup adverts

Adverts are used on the platform in the packages - you can offer the users of your platform an ad-free experience by selecting no adverts when creating or editing a package - allowing you to charge for the privielge. In the default themes that come with the system, you can edit the adverts by adding your advert code to these files in these locations:

• Basic Theme - edit the file resources/views/themes/basic/user/sidebar.blade.php on line 12
• Full Theme - edit the file resources/views/themes/basic/user_master.blade.php on line 69

Users and the embed code

When a user logs into the site, they will have the option to add a site to the system. By doing this, they can track any number of websites. The platform asks them for:

• Site name (used for reporting)
• Site URL (used for reporting)
• Site Timezone (used for reporting to make sure we display the correct data)

Once they have entered this information, they are then shown the site settings. On this page they can get the embed code they will need to place on every page on there website they wish to track.

The settings page on the Basic theme. Note the embed code box - this is the code they should use!

Once they place the code on there website - you should get data immediately.

Coding Standards

As wrAnalytics is based off the super popular PHP framework Laravel framework, we use its coding standards for the system, so we follow the PSR-2 coding standard and the PSR-4 autoloading standard.

This is tested everytime we auto-test by the package FriendsOfPHP/PHP-CS-Fixer and the command php php-cs-fixer.phar fix ./ --level=psr2 --dry-run to test if any files are found. We suggest if you are looking to develop the system you also do this.

Framework information

wrAnalytics used the Laravel framework, version 5.2. There are several reasons for this:

• Its the most popular framework for PHP at the moment, with many tutorials and how-to guides. This makes it perfect for us to use, as if you should find any issues, you should be able to fix it yourselves, rather than wait up to 24 hours for our support.
• We are experts since Laravel 3 (2013) - this enables us to be able to diagnose any issues really quickly to help you save money and time.
• We know the system inside and out, so we can get the best performance out of the system.
• Documentation for the framework is the best around - https://laravel.com/docs/5.2.

You can find out the packages we used to help with development in the Files and sources section.

Database models

A product of using the fantastic Laravel framework, is its amazing ActiveRecord implmentation for models for database tables. Each database table has a corresponding "Model" which is used to interact with that table. Models allow us to query for data in our tables, as well as insert new records into the table. The models we have created are below:

• \App\User - Location: app/User.php. We use this model on the front end to query if adverts should be shown to the user, as well as displaying user data.
• \App\Site - Location: app/Site.php. We use this model a lot on the front end when querying a site - such as getting data to display. A site is linked to a user by the column author_id.
• \App\Payment - Location: app/Payment.php. We use this model when saving or querying payments made.
• \App\Package - Location: app/Package.php. We use this model when saving or querying the sites packages. It is linked to a user by the column in the users table called package_id.

How are metrics collected?

We collect data with our Javascript embed that users can get for there sites in the settings area of there dashboard. When we process a hit, we forward the request to app/Http/Controllers/API/APIController.php and the method APIController@visitBeacon within it. It is within this function you should collect your data, and place it inside the $data array (line 71). To have this saved in the database, you'll need to create the corresponding row in the raw table within your database.

To access this data, you'll use the \App\Site model. Check out all the methods within this class (app/Site.php) to find helpers to get this data with regards to the time frames you need as well.

Installed themes

The live visitor page on the basic theme

The Basic theme is based on the fantastic Bootstrap framework. This theme is a great if you want to get to grips with making your own, as its heavily commented and has lots of cool features, such as graphs, live visitor views and easy to use datatables.

The front marketing page of the full theme

The Full theme is the theme we use for our clients. Its fresh, full width and has amazing tables, graphs and asthetics. It looks amazing on desktop as much as it does on mobile. Its also based around Bootstrap framework allowing you to quickly edit and add add features!

How to install themes

Always check with the installation instructions before installing a theme, as some themes will require some basic code editing skills to install correctly.

1. Drop the themes views in to the resources/views/themes folder.
2. Drop the themes styles (js, css, images) in to the public/assets/themes folder.
3. Go to the config/analytics.php file, and add the name of the folder to the themes variable.
4. In the settings page of the admin panel, select the new theme.

How to code a theme

The best place to start is by duplicating the Basic theme as its based on the popular bootstrap framework - allowing you to quickly get a theme up and together. To duplicate the theme, follow these instructions:

1. Go to resources/views/themes and duplicate the Basic folder. Make sure the name is the name of your new theme. These are the views and HTML that you wil be editing in the next steps.
2. Next, go to public/assets/themes and duplicate the Basic folder as well. Make sure its the same name as your theme name. This folder is the CSS, JS and images you'll be editing.
3. Go to the config/analytics.php file, and add the name of the theme to the themes variable. For instance, it might change to "themes" => ['basic', 'full', 'new_theme'],
4. Log in as an admin, go to settings and change the theme to the new one.
5. Now you can start to edit your new theme! If you need help and information on what to do with the Blade Templating Engine, please view this page: https://laravel.com/docs/5.2/blade.

Client only platform

One of the ways the platform can be used, is to keep control of all your sites for your clients, and give them access one by one to there own data. This is something we do with our clients, and they love the exclusivity of having an amazing system availble for them! To setup a client only system - follow these steps:

1. Setup the system by using the Get Started guides above. We use a custom sub-domain for our clients, something like http://clients.oursite.com.
2. Login as an admin, and navigate to the admin panel.
3. First, we'll set the default package to be unlimited. We don't want to limit our clients data! If you did want to charge your clients for more historical data - you might want to create another package.
4. Next, we'll go to settings. We change the System name to our company name, and also turn off Show Upgrade Panel (as we don't want our clients to know that that is an option), and we turn of User Registrations, as we'll be adding our clients manually.
5. Now that our system is ready, we'll add our first client. Click Users, then Add Account. Proceed to add your clients account - noting down the username and password. You'll want to give this to your clients in a few steps time. Choose which package you want to give them as well!
6. We give clients there accounts with the tracking code already working on there websites, but you can skip this step if they will add that code themselves. If you wish to add the clients tracking code for them, on edit user page, click Login as this user. Then, just as you was a normal user, add the clients websites, go to settings and add the embed code on the websites you wish to track. Our clients just love logging in and checking the data out and not having to worry if they did something wrong!
7. Finally, email over your clients with there username and password and a bit of text explaining how to use the site.

Something we also do, but thats not in the scope of the platform - is charge our clients for monthly reports. We go back into there accounts on the last Friday of the month, analyse the data, copy the graphs and send them some information on how well they have been doing in comparison to other months. We charge for this - maybe you can too?

How to admin the platform

Now you have the platform running - how do you run it? How do you know how many websites are on the system? How do you know if you are getting paid?

• To find out how many users you have, go to your admin panel, and click users. You'll see how many users you have on this page!
• To login as a user, and check out there sites etc, find there account in the admin users section by searching the table, and then click Login as this user. That function is perfect for helping your users if they have any problems!
• To checkout all your payments, go to Packages then click View Payments. In the top right, you'll see your total, and the page also has a table of all the payment information about your website.
• To get a comprehensive list of all the data your site has been collecting, view the stats page. You can view lots of your system data based on a date range on this page.
• Finally, you can view the system logs. This is found on the Settings page, then click View System Logs. Here is a list of all the information the system has logged such as payment info, user account deletion and site adding!

Platform FAQ's

Q. I am not getting any referers being displayed from Facebook, Google, Twitter etc

A. You need to serve your website and tracking from HTTPS to get this information. We advise all of our customers to be running a secure website with HTTPS - the best option, that is also free, is to implement https://letsencrypt.org on your website.

Q. I am developing my own theme and would like some help with methods, and code.

A. Check out the Basic theme - it is heavily commented, and gives you all the main functions, date systems and graphs you'll need. If you need anything else, contact us!

Q. What is a good 'render' time?

A. In your admin panel, you'll find a render time. This is the time it takes for the system to respond to the javacript being loaded, and stats being recorded, so you want to keep this as small as possible. Anytime less than 0.1 second is perfect!

Q. My location is being reported incorrectly!

A. To keep the render time as low as possible, we use an offline database to calculate locations. This is based off the GeoLite2 Free Downloadable Databases. If you wish to update the file used, please replace database/maxmind/GeoLite2-City.mmdb with the one (make sure its the GeoLite2 City) file on the MaxMind website.

Support Desk

Please remember you have purchased a very affordable web platform and you have not paid for a full-time web development agency. Occasionally we will help with small tweaks, but these requests will be put on a lower priority due to their nature. Support is also 100% optional and we provide it for your convenience, so please be patient, polite and respectful. Please visit our support system to ask a question. We aim to get back to you within 18 hours if you have purchased the platform - and upto 36 hours is its pre-sales.

Free Support for my items includes:

• Responding to questions or problems regarding the item and its features
• Fixing bugs and reported issues
• Providing updates to ensure compatibility with new software versions

Free Support does not include:

• Customization and installation services
• Support for third party software and plug-ins

Before seeking support, please...

• Make sure your question is a valid system Issue and not a customization request.
• Make sure you have read through the documentation and any related video guides before asking support on how to accomplish a task.
• Make sure to double check the Laravel docs
• If you have customized your system and now have an issue, back-track to make sure you didn't make a mistake. If you have made changes and can't find the issue, please provide us with your changelog.
• The majority of the time we find that the solution to people's issues can be solved with a simple "Google Search". You might want to try that before seeking support. You might be able to fix the issue yourself much quicker than we can respond to your request.

Files & sources

Included PHP frameworks, packages and sources

• 1. Laravel Link - Primary framework
• 2. jenssegers/agent Link - Browser agent parser
• 3. stevebauman/location Link - Location parser
• 4. braintree/braintree_php Link - Payment processor
• 5. This product includes GeoLite2 data created by MaxMind, available from http://www.maxmind.com.

Included Javascript / CSS frameworks, packages and sources

• 1. Bootstrap Link - Bootstrap CSS / JavaScript
• 2. Date Range Picker Link - Date range picker
• 3. Morris Link - Graphs
• 4. jQuery Link - Javascript libary
• 5. Datatables Link - Tables

Version history

Documentation version: 1.0.0

You can always find the version history (changelog.txt) file on wrAnalytics.zip folder or you can check changelog on code sale page.

-----------------------------------------------------------------------------------------
Version 1.0.0 - April 1st, 2016
-----------------------------------------------------------------------------------------

- Version 1 release